gibbonsecr: GUI User Manual

2.1 Basic setup

The basic data collection setup for an SECR analysis consists of a spatial array of detectors. Detectors come in a variety of different forms, including traps which physically detain the animals, and proximity detectors which do not. Using proximity detectors it is possible for an animal to be detected at more than one detector (i.e. recaptured) during a single sampling occasion.

The plot below shows a hypothetical array of proximity detectors, with red squares representing detections of the same animal (or the same group in the case of gibbon surveys) and black squares representing no detections.

The pattern of the detections (i.e. the pattern of the recapture data) gives us information about the true location of the animal/group; intuitively we would guess that it is probably near the cluster of red detectors. The plot below shows a set of probability contours for this unknown location, given the recapture data.

In the case of acoustic gibbon surveys the listening posts can be treated as proximity detectors and the same logic can be applied to infer the unknown locations of the detected groups. However, the design shown in the figure above would obviously be impractical for gibbon surveys. The next figure shows probability contours for a more realistic array of listening posts where a group has been detected at two of the posts.

(Back to top of section)
(Back to contents)

2.2 Estimated bearings

As you probably guessed from the previous section, using fewer detectors results in less information on the unknown locations. Fortunately however, SECR also allows supplementary information on group location to be included in the analysis – for example in the form of estimated bearings to the detected animals/groups. The next figure illustrates how taking account of information contained in the estimated bearings can provide better quality information on animal/group locations.

Using estimated bearings in this way can lead to density estimates that are less biased and more precise than using recapture data alone. Since the precision of bearing estimates is usually unknown, SECR methods estimate it from the data. This requires the choice of a bearing error distribution. The figure below shows two common choices of distribution for modelling bearing errors – the von Mises and the wrapped Cauchy – where the colour of the lines indicates the value of the precision parameter (SECR estimates the value of this parameter from the survey data).

The wrapped Cauchy is likely to perform better when there are a small number of large errors but when most of the estimates are close to the truth. The von Mises is likely to perform better there are fewer large errors.

(Back to top of section)
(Back to contents)

2.3 Estimated distances

TODO

(Back to top of section)
(Back to contents)

2.4 Detection functions

Another key feature of SECR is that the probability of detecting a (calling) gibbon group at a given location is modelled as a function of distance from the detector. This function – referred to as the detection function – is typically assumed to belong to one of two main types of function: the half normal or the hazard rate. The specific shape of the detection function depends on the value of its parameters, which need to be estimated from the survey data. The half normal has two parameters: g0 and sigma. The g0 parameter gives the probability at zero distance and the sigma parameter controls the width of the function. The hazard rate has three parameters: g0, sigma and z. The z parameter controls the shape of the ‘shoulder’ and adds a greater degree of flexibility. The figure below illustrates the shape of these detection functions for a range of parameter values.

(Back to top of section)
(Back to contents)

2.5 Detection surface

The association of a detection function with each detector allows the overall probability of detection by at least one detector during the survey to be calculated for any given animal/group location. The figure below illustrates this idea of overall detection probability using a heat map of a detection surface.

The region near the centre of the surface is close to the detector array and has the highest detection probability. E.g. in the figure above, an animal/group near to the detectors will almost certainly be detected. This probability declines as distance from the detectors increases.

(Back to top of section)
(Back to contents)

2.6 Effective sampling area

The shape of the detection surface is related to the size of the effective sampling area. Since the region close to the detectors has a very high detection probability, most animals/groups within this region will be detected and this region will therefore be almost perfectly sampled. However, regions where the detection probability is less than 1 will not be completely sampled as some animal/groups in these areas will be missed. The figure below illustrates this idea for a series of arbitrary detection surfaces.

The first plot in this figure shows a flat surface where the detection probability is 0.5 everywhere. In this scenario every animal/group has a 50% chance of being detected. If the area covered by the surface was 10km², then the effective sampling area would be 10km² x 0.5 = 5km². Using this detection process we would expect to detect the same number of animals/groups as we would if we perfectly sampled an area of 5km². In the second plot in the figure above half of the area is sampled perfectly and the other half is not sampled at all, so this has the same effective sampling area as the first plot. The third plot has a detection gradient and isn’t as intuitive to interpret. However, the way we calculate the effective survey area is to calculate the volume under the detection surface. The third plot has the same volume as the other two, so it has the same effective area.

(Back to top of section)
(Back to contents)

3.1 Launch from R

install.packages(c("CircStats", "dplyr", "MASS", "secr", "tcltk2"),
                 dependencies = TRUE)

install.packages("https://github.com/dkidney/gibbonsecr/raw/master/binaries/gibbonsecr_1.0.zip", 
                 repos = NULL, type = "win.binary")

install.packages("devtools", dependencies = TRUE)
devtools::install_url("https://github.com/dkidney/gibbonsecr/raw/master/binaries/gibbonsecr_1.0.tgz")

library(gibbonsecr)
gibbonsecr_gui()

3.2 Launch from a desktop icon

4.1 CSV files

As a minimum you need to prepare a detections file and a posts file. You can also include an optional covariates file. Advice on how to structure these files is given in the sections below. All raw data files need to be in .csv format. The file paths to your data files can be entered manually into the text entry boxes in the CSV files section, or you can navigate to the file path using the ... button.

4.2 Data details

Once the paths to the data files have been entered, select the relevant units from the Data details dropdown boxes for your estimated bearings data (and estimated distances data if it was collected). (Note that the current version of the software only allows Type = continuous since interval methods for bearings and distances haven’t yet been implemented.)

(Back to top of section)
(Back to contents)

4.3 Data buttons

Once the paths to your data files have been added and the data details checked, you can then press the Import button. If your data imports successfully then a summary print out should appear in the output window. You can re-print this summary at any time by pressing the Summary button.

The screenshot below shows an example of some summary output after a successful data import.

**SCREENSHOT**

(Back to top of section)
(Back to contents)

5.1 Mask size and resolution

There are two main settings you need to consider when defining a mask – the buffer and the spacing – which you can specify in the Mask tab.

5.2 SHP files

The Mask tab also allows you to upload shapefiles in order to attach spatial covariate values to each of the mask points for use in model formulas.

NB: Make sure the projection units in your .shp files are compatible with the coordinate system used in your posts data file

5.4 Mask buttons

TODO

(Back to top of section)
(Back to contents)

6.1 Model options

The first section in the Model tab contains dropdown boxes where you can choose between different detection functions and different distributions for the estimated bearings and distances.

• Detection function – choose either the half normal (the default) or the hazard rate
• Bearings distrbution – choose from the von Mises (the default), the wrapped Cauchy, or none
• Distances distribution – choose from the gamma (the default), the log-normal, or none

Setting the bearings/distances distribution to none means that the bearings/distances data will be ignored in the analysis. Setting both bearings and distances distributions to none will result in a conventional SECR model being fitted using only the recapture data.

(Back to top of section)
(Back to contents)

6.2 Model parameters

The next section in the Model tab provides various options for refining your model. Each row in this section relates to a particular parameter in the SECR model.

• D – The number of groups per square kilometre
• g0 – The detection function intercept parameter (see Section 2.4 )
• sigma – The detection function scale parameter (see Section 2.4 )
• bearings – The parameter of the distribution for the bearing errors (see Section 2.2 )
• distances – The parameter of the distribution for the estimated distances (see Section 2.3 )
• pcall – The probability of a group calling on a given day

Don’t worry if you forget these definitions, hovering your cursor over the row labels on the user interface will open a temporary help box to give you a reminder.

(Back to top of section)
(Back to contents)

habitat + weather

6.3 Model buttons

There are four button at the botton of the Model tab:

1. Fit – Use this button to fit the model once you are happy with your model specification. Once your model is fitted a summary will appear in the output console.
2. Summary – Use this button to reprint the model summary
3. Coef – This prints a summary of the raw model coefficients
4. Predict – This allows you to predict the value of each model parameter. If you have used covariates in model formulas a pop-up box will appear allowing you to choose specific values of covariates (e.g. you may wish to predict density for all levels of a habitat covariates)

(Back to top of section)
(Back to contents)

8.1 AIC

A common way of choosing between competing models is to use something called the AIC score. This is a number that can be calculated from the fitted model which tries to measure how well the model balances having a good fit to the data whilst not being overly complex. The AIC score can be found at the bottom of the model summary printout (which is displayed after pressing the model Summary button at the bottom of the Model tab).

When using AIC it is important to bear in mind the following points:

• Lower AIC scores are preferred. For example, if model A has an AIC score of 10, and model B has a score of 100, then model A would be preferred to model B.

• Negative scores are preferred to postitive scores. For example, if model A has an AIC score of -10 and model B has a score of -100, then model B would be preferred to model A.

• Diffences of 2 or more are meaningful. This is a general rule-of-thumb for deciding between models with different number of coefficients. If the difference is less than this then you should be conservative and keep the model with the fewest coefficients. For example suppose you fitted model A with an intercept-only formula for density (i.e. no covariates) which had an AIC of 100. Then suppose you fitted a model B with habitat as a covariate for density (e.g. D ~ habitat) which had an AIC of 99. The difference is only -1 which isn’t a big difference, and according to the rule of thumb the difference isn’t large enough to prefer model B over model A. Now imagine that you fitted a third model, model C, using altitude as a covariate for density (e.g. D ~ altitude) which had an AIC of 95. The difference between model A and model C is 5, so according to the rule of thumb model C would be preferred.

• Only models fitted to the same data can be compared using AIC. For example, you could use AIC to help you decide whether or not to use the von Mises distribution or the Wrapped Cauchy distribution to model the bearing errors, because both models would have been fitted using the estimated bearings data. However you could not use AIC to compare two models where one used a bearing error distribution and one used no bearing error distribution, since the estimated bearings data would be used in the first model but ignored in the second models (the precision of the density estimate might be a better to make a decision in this case). For a similar reason, you also should not use AIC to compare models fitted using different masks.

• The magnitude of the AIC score tells you nothing about how good a model is. The difference in AIC between two competing models helps you decide which one is better, but they might both be poor models. Unfortunatley on of the disadvantages of SECR is that there is currently no means for calculating model goodness-of-fit statistics.

(Back to top of section)
(Back to contents)

8.2 Model plausibility

Whilst AIC can be extremely useful it shouldn’t be used blindly and you should also ensure that any preferred model is also plausible. For example, model A might have a lower AIC score than model B, but if model A looks entirely unrealistic (e.g. given your knowledge of the study system) then you should discard it. For example, a fitted bearing error distribution which implied that errors as large as 180 degrees were highly probable might be ignored if such an outcome is known to be very unlikely under normal field conditions.

(Back to top of section)
(Back to contents)

9.1 The Help menu

9.2 The Workspace menu